Add HTTP QUERY method and Accept-Query header references by gomestai · Pull Request #44568 · mdn/content

gomestai · 2026-06-24T16:43:06Z

Description

Adds documentation for the HTTP QUERY method defined by RFC 10008.

This PR adds:

A dedicated QUERY method reference page
An Accept-Query header reference page
Updates to the HTTP request methods landing page, including the method list and safe/idempotent/cacheable table

Motivation

RFC 10008 defines QUERY as a safe and idempotent HTTP method that carries request content and returns the result of processing that content. It fills the use case where a request is read-only like GET, but the query input is too large or complex to fit comfortably in the URI.

Additional details

This PR does not add BCD data because there is no explicit browser integration for QUERY yet. The new reference pages use spec-urls metadata instead.

The RFC defines the response header as Accept-Query; this PR uses that name for the header reference page.

github-actions · 2026-06-29T03:50:22Z

Preview URLs (3 pages)

External URLs (1)

URL: /en-US/docs/Web/HTTP/Reference/Headers/Accept-Query
Title: Accept-Query header

https://www.rfc-editor.org/rfc/rfc9651.html (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-07-17 04:04:34)

hamishwillee · 2026-06-29T04:52:35Z

Thanks @gomestai .

Thinking aloud:

rfc10008 was only accepted a few weeks ago. As I understand it there isn't any specific browser integration as such. There is interest in allowing it to be specified in forms in Support QUERY method in form submissions whatwg/html#12594 - but it isn't clear whether that will happen - similar suggestions for other methods have existed for years.
From the browser point of view I think you can use this now in a fetch request by specifying the method in your RequestInit or Request.method. Fetch only expects a name (you can use "CABBAGE" if you wanted) and because it isn't a CORS safelisted method the preflight should be handed for you.
However I'm not sure about the rest of the internet, such as CDNs, caches, server frameworks such as Express, Django, whatever.
Looking at the PR, yes, we will need a specific QUERY page.
I am not sure about BCD yet. I don't think it gets a record because there is no direct integration.

Upshot, I'm going to see if I can get a little more information on this topic and get back to you. MIght not be very quick.

hamishwillee · 2026-06-30T02:55:40Z

@gomestai So I've had a short discussion on this.

Browsers don't have explicit support (at least yet) so there is no need for a BCD update.
Support is likely to be mixed. Most middlware and servers are unlikely to use a strict whitelist of methods and will likely just work, but caches may well need update.

What you have done is a first step - this really needs

a page like GET (or or one of the other methods), with the right format and examples
- This will need the spec-url key in the metadata to link to the spec, because there isn't a browser-compat key to use (as no BCD)
A page for Allow-Query header.

This is a non-trivial bit of documentation. Are you willing to take it on. We could stop at this point if you think this is more than you are willing to commit. However it isn't all that useful at this point because until we have the page there is no spec link or detail on how it used.

gomestai · 2026-07-06T19:09:56Z

@gomestai So I've had a short discussion on this.

Browsers don't have explicit support (at least yet) so there is no need for a BCD update.

Support is likely to be mixed. Most middlware and servers are unlikely to use a strict whitelist of methods and will likely just work, but caches may well need update.

What you have done is a first step - this really needs

a page like GET (or or one of the other methods), with the right format and examples

This will need the spec-url key in the metadata to link to the spec, because there isn't a browser-compat key to use (as no BCD)

A page for Allow-Query header.

This is a non-trivial bit of documentation. Are you willing to take it on. We could stop at this point if you think this is more than you are willing to commit. However it isn't all that useful at this point because until we have the page there is no spec link or detail on how it used.

Thanks for the detailed guidance. I just saw this.

Yes, I’m happy to take this on. I’ll start on the method page and the Allow-Query header page tomorrow.

betweencode · 2026-07-09T13:04:04Z

Hi everyone! I stumbled upon this PR while looking at the HTTP methods index. Since RFC 10008 was recently accepted, I was wondering: is it advisable to start experimenting with the QUERY method in production soon, or should we wait for broader CDN/cache and server framework support? Thanks for your amazing work documenting this!!!

hamishwillee · 2026-07-13T00:23:41Z

Yes, I’m happy to take this on. I’ll start on the method page and the Allow-Query header page tomorrow.

Thanks @gomestai

github-actions · 2026-07-13T00:24:13Z

    Requests using `GET` should only retrieve data and should not contain a request {{Glossary("HTTP Content", "content")}}.
+- {{HTTPMethod("QUERY")}}
+  - : The `QUERY` method requests that the target resource process the request content in a safe and idempotent manner, returning the result in the response.
+   It is similar to GET, but allows request body content with defined semantics.


[mdn-linter] _{reported by reviewdog 🐶}

Suggested change

It is similar to GET, but allows request body content with defined semantics.

It is similar to GET, but allows request body content with defined semantics.

hamishwillee · 2026-07-13T00:32:52Z

Hi everyone! I stumbled upon this PR while looking at the HTTP methods index. Since RFC 10008 was recently accepted, I was wondering: is it advisable to start experimenting with the QUERY method in production soon, or should we wait for broader CDN/cache and server framework support?

@betweencode From my response above:

Support is likely to be mixed. Most middleware and servers are unlikely to use a strict whitelist of methods and will likely just work, but caches may well need update.

No one can answer this except you, since it depends on what server frameworks and infrastructure you're using. The advice above seems to indicate that it should mostly just work.

IMO there is nothing to stop you experimenting now if you have use cases that would benefit, but you'd want to do robust testing before deploying to production.

gomestai · 2026-07-16T10:38:15Z

I added the header page as Accept-Query rather than Allow-Query, since RFC 10008 defines the field as Accept-Query. Please let me know if you intended a different page/name here.

Adds the HTTP QUERY method defined by RFC 10008 to the HTTP request methods landing page. RFC 10008 defines QUERY as a safe and idempotent HTTP method that carries request content and returns the result of processing that content. The request method table is updated accordingly.

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

hamishwillee · 2026-07-17T05:58:04Z

 slug: Web/HTTP/Reference/Headers/Accept-Query
 page-type: http-header
-spec-urls: https://www.rfc-editor.org/rfc/rfc10008.html#section-3
+spec-urls: https://www.rfc-editor.org/info/rfc10008/#name-the-accept-query-header-fie


FYI the /info URLs are the ones that get updated to have a rendered description in the spec table. That hasn't been added yet but will be at some point. In any case though, we get to see the URL in this case, which is at least a little interesting.

hamishwillee · 2026-07-17T06:16:59Z

+This allows a `QUERY` request to be retried automatically without concern that it will cause additional changes to the target resource.
+
+`QUERY` is useful when the query input is too large or complex for the target URI's query component.
+The request's {{HTTPHeader("Content-Type")}} header is required and determines how the request content is interpreted by the target resource.


Thanks @gomestai This is a good start. There are some important omissions with respect to the spec though.

Equivalent resource / Content-Location / Location (§2.2–2.4) . It is an important difference between POST/GET and this method that you can get back an URL with a temporary loction for getting the same data again and/or rerunning the query on current data.
2.Content negotiation / 415 handling (§2.1) — servers reject unsupported Content-Type with 415, and Accept-Query is one way clients discover what's supported. The two pages currently connect only via a "See also" link, not in the body text. You might have a specific example for this in QUERY.

Redirection and conditional requests probably worth a paragraph.

Caching needs to cover that you can cache (like Get) but you have to use the body in the cache key. It stands to reason of course, but I wouldn't have though of it if I hadn't read the spec.

Not sure if it is worth talking about range requests.

This particular description is slightly messy in that it has "QUERY is useful when the query input is too large or complex for the target URI's query component.". What query input? Here you are drawing a relationship to using this for search queries using GET that hasn't been established.

The spec abstract describes it very abstractly. I think we might be best starting with a line like this "this is what it is intended for" then commenting on the properties that make it suitable for that purpose.

If there ends up being too much in the top section we can add a Description section before the examples. We should look at all the examples, including those in the appendices and see what you can learn from them - might have some stuff worth capturing.

Does that make sense? If it is too much, let me know and perhaps I can help you extend it

PS MDN is usually a human readable and website developer-centric version of the spec, needed because often specs are written primarily for browser vendors (in this case the spec is actually quite readable).

In any case, we still don't just copy the spec - but we do need to copy the most important nuances of the features use in an accessible way. That's why I lean to starting with "this is mostly for implementing queries that might otherwise be too big to put in a GET", and then covering further details.

This is also the first time there's been a new HTTP method in ages. So there will be eyes on this and we want to make sure we give users the head start they need to use it effectively.

Thanks, this makes sense. I’ll expand the QUERY page to cover the missing pieces from the spec in a more developer-focused way: equivalent resources with Content-Location/Location, Accept-Query discovery and 415 handling, caching behavior, redirects, and conditional requests.

I’ll also rework the intro so it doesn’t imply that QUERY is only for replacing long GET query strings, but presents that as one common use case.

gomestai requested a review from a team as a code owner June 24, 2026 16:43

gomestai requested review from hamishwillee and removed request for a team June 24, 2026 16:43

github-actions Bot added Content:HTTP HTTP docs size/xs [PR only] 0-5 LoC changed labels Jun 24, 2026

hamishwillee reviewed Jun 30, 2026

View reviewed changes

Comment thread files/en-us/web/http/reference/methods/index.md Outdated

hamishwillee mentioned this pull request Jul 13, 2026

Add HTTP QUERY method #44665

Open

github-actions Bot reviewed Jul 13, 2026

View reviewed changes

github-actions Bot added size/m [PR only] 51-500 LoC changed and removed size/xs [PR only] 0-5 LoC changed labels Jul 16, 2026

gomestai changed the title ~~Add QUERY method description to HTTP methods index~~ Add HTTP QUERY method and Accept-Query header references Jul 16, 2026

gomestai and others added 6 commits July 17, 2026 14:05

Update files/en-us/web/http/reference/methods/index.md

fe7fd97

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

docs(http): add QUERY method reference

b4dcb62

docs(http): refine QUERY references

0569ee8

docs(http): polish Accept-Query reference

2365da7

docs(http): clarify Accept-Query media types

961cb96

hamishwillee force-pushed the patch-1 branch from 7b9047c to 961cb96 Compare July 17, 2026 04:05

Minimal additions

2d823bc

hamishwillee reviewed Jul 17, 2026

View reviewed changes

minor tidy2

d465d7c

hamishwillee reviewed Jul 17, 2026

View reviewed changes

	It is similar to GET, but allows request body content with defined semantics.
	It is similar to GET, but allows request body content with defined semantics.

Uh oh!

Conversation

gomestai commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Uh oh!

github-actions Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hamishwillee commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

hamishwillee commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gomestai commented Jul 6, 2026

Uh oh!

betweencode commented Jul 9, 2026

Uh oh!

hamishwillee commented Jul 13, 2026

Uh oh!

github-actions Bot Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

hamishwillee commented Jul 13, 2026

Uh oh!

gomestai commented Jul 16, 2026

Uh oh!

hamishwillee Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

hamishwillee Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

hamishwillee Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

gomestai Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gomestai commented Jun 24, 2026 •

edited

Loading

github-actions Bot commented Jun 29, 2026 •

edited

Loading

hamishwillee commented Jun 29, 2026 •

edited

Loading

hamishwillee commented Jun 30, 2026 •

edited

Loading